-- card: 7952 from stack: in
-- bmap block id: 0
-- flags: 0000
-- background id: 2795
-- name: SubLaunch


-- part contents for background part 1
----- text -----
XFCN

-- part contents for background part 22
----- text -----
SubLaunch(programName,docName)

-- part contents for background part 13
----- text -----
    •  SubLaunch(programName,docName)* - sublaunches the program with optional attached 
        document.  Both HyperCard and the specified program will then be running, memory 
        permitting (at least 2 Meg!).  If the arguments have no colons in them (not a pathname), 
        then the “Look for applications in:” etc. cards in the Home stack are consulted. 

SubLaunch return 0 for success, negative numbers for Operating System errors, and small positive numbers for parameter errors, or lack of memory. To see how to handle this, and how the XFCNs can be used in concert, take a look at the “InvokeApplication” and “OsErr” handlers* below. InvokeApplication also fixes HyperCard bugs* when under MultiFinder.

on InvokeApplication progName,docName,noSubLaunch
  global documents
  if MultiFinder() is false then
    if docName is empty then
      open progName
    else
      open docName with progName
    end if
  else
    if IsRunning(progName) is true then
      -- Can't attach a document in this case without invoking
      -- Tempo or QuicKeys. See the “PostEvent” stack for details.
      doMenu progName
    else
      -- Not running. Launch or sublaunch it.
      if the shiftKey is down or noSubLaunch is true then
        -- Override: don't sublaunch, just do a normal launch.
        if docName is not empty then
          -- Need to move the document up to the volume root for this
          -- to work properly due to MultiFinder/Hypercard bug.
          if NumberOfChars(":",docName) is 0 then
            -- Filename needs expanding
            put GetFullPath(docName,documents) into docName
            if docName is empty then
              -- one reason for this would be a previous call that
              -- moved the document up to the root, and the root isn't
              -- on the document search path
              answer "Can't find the document" with "OK"
              exit InvokeApplication
            end if
          end if -- end NumberOfChars
          
          -- Is this document at the root of the volume?
          if FileAtRoot(docName) is false then
            -- Need to move it to the root. Start by computing the
            -- name of the volume.
            put VolumeName(docName) into vol
            if vol is empty then exit InvokeApplication
            
            put MoveFile(docName,vol) into err
            if err is not 0 then
              OsErr err -- report file i/o error
              exit InvokeApplication
            end if
            
            -- Document is now at the root. All we need to do is find
            -- out the new name for the document.
            put vol & LastPathComponent(docName) into docName
          end if -- end FileAtRoot
          
          open docName with progName
        else
          -- No document. Just run the application.
          open progName
        end if -- end docName not empty test
        
        exit InvokeApplication
      end if      -- end shiftKey/override
      
      if docName is empty then
        put SubLaunch(progName) into err
      else
        put SubLaunch(progName,docName) into err
      end if
      if err is not 0 then
        if err < 0 then
          OsErr err
        else if err is 1 then
          -- Parameter error?
          answer "Parameter error in sublaunch call" with "OK"
        else if err is 2 then
          -- System error encountered in sublaunch
          answer "Insufficient memory (or already running?)" ¬
          with "Failed"
        end if
      end if
    end if
  end if
end InvokeApplication

-- OsErr: for displaying Operating system error codes returned by
-- Sublaunch, RenameFile, MoveFile and DeleteFile XFCNs.

on OsErr err
  -- Translate the most common ones
  if err > 0 then -- XFCN convention
    put "Parameter error with function" into errstr
  else if err is -59 then
    put "Problem during rename" into errstr
  else if err is -54 then
    put "Attempt to open locked file for writing" into errstr
  else if err is -46 then
    put "Volume locked by software" into errstr
  else if err is -45 then
    put "File locked" into errstr
  else if err is -44 then
    put "Volume locked by hardware" into errstr
  else if err is -43 then
    put "File not found" into errstr
  else if err is -37 then
    put "Bad volume or file name" into errstr
  else if err is -36 then
    put "I/O error" into errstr
  else if err is -35 then
    put "No such volume" into errstr
  else if err is -34 then
    put "Disk is full" into errstr
  else if err is -49 then
    put "File already open for writing" into errstr
  else
    put "Failed with error" && err into errstr
  end if
  answer errstr with "OK"
end OsErr